Advanced UI Mode

In this chapter we will create a new license project in advanced mode to protect the nodepad2 test case.

New Project

Launch the SoftwareShield IDE, switch to Advanced GUI Mode, there are several ways to create a new project:

• press New Project button on toolbar;
• click the main menu item "File => New Project";
• press keyboard short-cut Ctrl + N;

Either way will pop up the new project dialogbox:

Let's fill in the form in the following steps:

• Product Name: This is a string name of your product.

  By default, it will be used as Windows title of the license UI so it is better to have a meaningful short string. It also serves as the name of the default project directory so cannot have invalid characters for Windows file system. When you manage license project in CheckPoint Web management portal, the product name is the title of each application so you must ensure it is unique within your managed products.

  Here in this turorial we set it to "Advanced Tutorial Of nodepad2".

• Project Type: There are several kinds of license project for different scenarios, please refer to License Project Type for more details.

  Most likely you will choose the Standard type because it can easily protect application without SDK integration. We just use the default Standard project type in this test case.

• Project Location: The root directory of all license projects.

  It is convenient to put all your license projects inside the same file system location, so they can be located and backed up easily. On Windows, the default project location is a sub-directory (named SoftwareShield) under your user document folder.

• Project Directory: The sub-folder name for the new project under the project location.

  By default, it is the same as Product Name in the first step, however it can be any valid path name and the final license project will be created in the folder: (Product Name)(Product Directory)</PATH>

  If the sub-folder does not exist, it will be created later, if the sub-folder already exists, the IDE will give you a warning and need your confirmation before it wipes off all existent files under this folder.

• Game Source Directory: Let the IDE knows where to copy the original application binaries.

  IDE assumes that all directories and files under the source directory you specified are application binaries, and will recursively copy the directory content to the license project's internal source folder ((Product Directory)\src), so if your application is a single executable file, you have to create a folder first and copy the file into it.

  After the license project is created, the original Game Source Directory is not needed any more. the license project itself is now portable and self-contained, so it can be backed up, moved to other folder or any machine to continue editing and building.

• Main Executable: The Start-up executable of the application.

On Windows platform, the executable file is a .exe file or dynamic library file (.dll, *.ocx), the Start-up executable file is the first file launching the application. For a simple application, there may only be one executable file, but for some complex games with multiple executables, when the "Browse" button is pressed the IDE will detect all available executable files in the open file dialog, so you must choose which one is the start-up one.

In this tutorial, the only choice is the single executable file: Notepad2.exe

• Executionn Mode: How to partition the execution of license UI with the application itself to avoid possible runtime conflicts. Please refer to Execution Mode for details.

Because Notepad2 is a normal GUI application, we do not need to worry the built-in license UI could cause problem to the application execution if they are executed in the same process, so we select P1S2 in this test case.

If your application is a video game, or a full screen application, it is safe to choose P1S3 first, when testing wrapped game, you can select other execution mode to see if they also work fine.

• License Model: The license model to be used for the default (first) entity.

  When creating a new license project, SoftwareShield IDE will automatically create a new entity for this license project, so here you can select which kind of built-in license model to protect this first entity.

  After the license model is selected, the license-specific parameters are displayed so you can edit these parameters as needed.

  In this tutorial, we choose Expire By Period license model, and in order to demonstrate what will happen when the license is expired, we intentionally set the trial period to a very small value: 30 seconds.

The finished new project GUI looks like:

Finally, we can press Ok button to create the new license project for our tutorial, the IDE will:

1. Create a new project directory;
2. Initialize the internal License Project Layout;
3. Copy original application binaries to "(project directory)\src";
4. Create a new license file with your initial settings;

Edit Project settings

If everything is successful, the SoftwareShield IDE will open the fresh new license project in advanced mode:

As a quick tutorial, at this stage we could have started building the project directly, but before doing that, we will spend a while to introduce what can be done to customize the new project settings.

• Product ID: SoftwareShield IDE has initialize a random unique UUID as the Product ID.

  The product-id is a globally unique string identifying each license project in server database, it remains read-only on the IDE GUI, the only way to change it is by manually editing the license project file (*.lpj) in a XML text editor; it is highly recommended not to change its value unless you are pretty sure what you are doing.
  

• Product Description: An optional string description; You can use it as an internal memo for the license project.

• Build ID: For a new project, its build-Id starts from zero, indicating that the project has not been built yet. After building project, this field will be updated automatically to the current build-id value.

• Publish Status: Because the project is not uploaded to the CheckPoint license server, its publish status is: Not Published After publishing for the first time, the field will be displayed as Published.

• Sample SN: A simple serial number for internal QA. If a project is already published to \emph{CheckPoint} server, after each build, a serial number will be created automatically which can be used to unlock the first entity via online activation. It is blank since the new project is not built and uploaded yet.

• Entity Name: A string name of entity. The default one will be named as E1, E2, E3, etc. The entity name is also displayed in built-in license UI to identify an entity, You can optionally change it to a more meaningful and user-friendly name.

• Entity Description: An optional memo for an entity.

• Auto-Start on Launch: Specify if the entity is of an Auto Start Entity.

  Basically if we are using Standard license project type, there must be at least one auto-started entity so that the built-in license UI can have a chance to pop up when application launching.

  For other project types, you may prefer manually accessing an entity in source code by calling SDK api, so that the runtime behavior between unwrapped and wrapped application is almost the same.

Build Project

Let's build the project by clicking the IDE's main menu item "Build => Build Project", or clicking the "Build Current Project File" button on the toolbar:

While project building, all build messages are redirected to a build output pop-up window, after the project building is successful, the build output window will be closed automatically, it can be shown again by clicking the main menu item "Show Output" at the right top corner of the IDE.

At the end of build log, you can find the following message indicating everything is good for this build:

IDEConnect::gsWrap >> Ironwrapper runs successfully done!

After the build, on the IDE UI, we can see the _Build ID_field is now displaying "1":

Launch Wrapped Application

Now we can test the SoftwareShield protected application for the very first time!

You can launch the protected application by pressing Test Run button, or clicking the menu item ("main menu => Build => Run => Clean and Run Protected Game").

There are different ways of launching app from SoftwareShield IDE:

1. Run Game Source ( Main menu => Build => Run => Run Game Source )

IDE launches the original app binary inside the project_dir/src/ folder; it allows you to test the behavior of unwrapped app, which is important to make sure that the original app works fine before wrapping, you can also compare the runtime behavior of original app with wrapped app to verify that the original app functions are not changed by the protection.

2. Clean and Run Protected Game ( Main menu => Build => Run => Clean and Run Protected Game );

IDE cleanup the local license information before launching the protected app. It is useful during QA that you want to test the app multiple times from the beginning (as if the app is installed and launched for the first time), if the app is unlocked during the test, the license cleanup will roll back the app's license to the original initial status, so the license GUI will popup again for you to test other features.

3. Run Protected Game Directly ( Main menu => Build => Run => Run Protected Game Directly );

IDE launches the protected app inside the project_dir/Release/Deploy/ folder; after test running, the application's license data has been persisted to the local test machine, launching in this way will also you to test the license logic (applied serial number, activation, serial revoking, etc.) works as expected.

You can also browse to the project's release folder (Main Menu => Build => Browse => Release Directory) and launch the protected application manually by double clicking the protected exe in the "Deploy" folder.

When the protected app launching, the default license startup UI looks like as following:

You can:

• Launch : try launching the protected app in trial mode; This button is enabled when the license is not expired.
• Activate: Activate the app (online or offline);
• Transfer: Revoke serial number or transfer license to another machine;
• Buy Now: Launch the default web browser to go to your BuyNow url; You can also customize the UI to make online purchase inside the popup screen, which allows the workflow of in-app integration of purchase and activation.
• Exit: Exit the app launching.

See Wrapped App Expires

In this demonstration project we intentionally set a very short trial period (30 seconds) so you can even wait a while to see if the application will terminate automatically after trial period expires.

Press Launch button to try the protected app, the Notepad2 application will run normally, you can type some words in the text editor for a while:

until the 30 seconds are elapsed, oops, the editor closes automatically and the following exiting-UI pops up:

After the app has expired, you have only 3 choices:

• Activate: Activate the app (online or offline);
• Buy Now: Launch the default web browser to go to your BuyNow url;
• Exit: Exit the app launching.

Up to now everything works fine, the app launches normally, the text editor works as usual, the trial mode expires properly. We can now go a step further to demonstrate how to activate the app.

At this stage we cannot do online activation because the project has not been registered on the server side, let's do it in the next section first.

Publish Project

You can publish the project to license server by either of the following ways:

• Press the "Publish To CheckPoint Server" button on the toolbar.

• pressing the "Publish..." button on the main UI;

• Main Menu => Tools => CheckPoint => Publish to CheckPoint Server;

The project publishing GUI needs your CheckPoint online account information to log in to the server.

After pressing the "Publish" button, if the publishing is successful, a message box will pop up telling you a project rebuild will start up after the message box is closed.

The rebuild is necessary because after successful publishing, the server's information must to be included in the protected exe so that your customers can activate the application online.

After the rebuild, you will find the following changes:

1. Publish Status is now Published;

   Publish Button is also disabled: Each project can publish only once, after the first time publishing, the IDE will publish every new rebuild automatically.

2. Build UD is now 2; Every successfully project build will increase the build ID automatically.

3. Sample Serial Number gets a valid serial: "FB12-9F79-401D-8CA0".

For each project rebuild, if the project is already published, the IDE will ask the server to create a new sample serial number which has a 1000 activation limit and can be used to test the protected application.

Now you can test run again to see if online activation works.

Activate App Online

1. Launch the app again by pressing the "Launch" button on the toolbar, the License Startup UI pops up.
2. Press "Activate" button, the license activation UI renders as following:

When the UI starts rendering, the javascript code on the page tries to connect the CheckPoint license servers to make sure the servers are alive.

Now you can:

1. Goes to the IDE to copy the test serial number to clipboard (your customers might copy the serial number from emails sent to them by online store), and press the Paste button, or simply input the serial in the text box on the page;

2. Press the Activate button:

This is the video recording of the whole process of online activation:

After the activation, you can verify the app is fully licensed (no more license startup UI pops up) by Run Protected Game Directly.

Activate App Offline

The online activation works great in most cases, however, there are special use senerarios that the online activation cannot be used:

• The Internet connection not available

  The machine your app is being installed does not have an internet connection. It could happen when the machine is part of a secured private LAN.

• The In-App activation not supported

  Due to security reasons your app is somehow blocked by firewall. The LAN administrator only allows specified web browser connect to internet and other apps are prohibitted to visit public web site.

1. Launch the protected application;

2. Press the "Activate" button;

Before pressing the "Activate" button, in order to test offline activation, we can simulate this situlation by unplugging our RJ45 cable or disable the network connection temparaily.

Now that we are disconnected to internet, let's click the Activate button now:

As expected, the online activation GUI displays an error message indicating the server cannot be connected, and the Offline button is available as fall-back.

Pressing the Offline button will guide us to the offline activation page:

The following information is rendered on the UI:

• Request Code: This is the code the customer have to send to you for a valid license code;

• Web Activator: as mentioned above, the current installing machine cannot perform online activation normally due to various reasons, however, instead of letting your customers contact your support team to generate the license code manually, for each uploaded online projects the CheckPoint server hosts a project-specific web activation page so that the customer can generate the license code by himself/herself without your support.

  Even if the machine does not have internet connection, the customer can also use another machine or other mobile devices to get an offline license code.

In this tutorial, we'll use the "Web Activator"; before doing that, let's enable our local internet connection first, please plug-in your internet cable or enable the previously disabled network connection, the click the "Web Activator" link:

Your default web browser is launched and you can see the request code previously displayed in the offline activation UI is automatically populatede in the web page!

Let's input the test serial number as we do in the online activation, and press the "Get License Code" button, after waiting for a little while, the license code is generated by license server:

Please copy the generated license code (H77P-QKCB-9FOA-AP3Z-XZ5U), go back to the offline activation UI, paste the license code, and press the "Activate" button

Congratulations, you have activate the app by offline activation!